home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Internet Tools 1993 July / Internet Tools.iso / RockRidge / ip / trace / tcpdump-2.2.1 / bpf / README < prev    next >
Encoding:
Text File  |  1992-06-02  |  6.4 KB  |  159 lines
  1. Sun Jan 26 20:23:52 PST 1992
  2.  
  3. This directory contains the files necessary to install the
  4. Berkeley Packet Filter (BPF) in a BSD (or BSD-like) kernel.
  5. BPF is derived from the Stanford/CMU enet packet filter that was 
  6. distributed with 4.3BSD.  We have made no efforts to keep the two
  7. interfaces compatible.
  8.  
  9. BPF has been tested on hp300's running BSD Tahoe/Reno, Sparcstations 
  10. running SunOS 4.1, Sparcstations running BSD Reno, and Sun 3's running
  11. SunOS 3.5.  We have configured it into the BSD Lance ethernet driver, 
  12. the Sun LANCE and Intel drivers, and our (soon to be released) SLIP driver
  13. (BSD, SunOS 3.5 and 4.1).  The modified BSD driver is included in this
  14. distribution, however, the Sun drivers cannot be made available.  If
  15. you have SunOS source, you can apply the context diff in
  16. sunif/if_le.c-sunos4.1-diff to the 4.1 lance driver (net/if_le.c).
  17.  
  18. There are patches for various flavors of loopback interface in
  19. {net,netinet}/if_loop.c*.
  20.  
  21. Note that there have been quite a few changes since the version released
  22. with tcpdump-2.0.  If you have modified drivers, you will need to update
  23. them.  In particalar, the calling sequence for bpfattach() has changed.
  24.  
  25. Follow these steps to install bpf into a new kernel:
  26.  
  27. (1)    Add the following line to your config file.  The parameter
  28.     is an upper bound for two things: the number of simultaneuous open 
  29.     files, and the number of hardware interfaces attached to BPF.
  30.  
  31. pseudo-device   bpfilter 16
  32.  
  33.     Add these lines to conf/files:
  34.  
  35. net/bpf.c        optional bpfilter
  36. net/bpf_filter.c    optional bpfilter
  37.  
  38. (2)    Copy these files into /sys/net:
  39.  
  40. bpf/net/bpf.c
  41. bpf/net/bpf_filter.c
  42. bpf/net/bpf.h
  43. bpf/net/bpfcodes.h
  44. bpf/net/bpfdesc.h
  45.  
  46. (3)    Install bpf.h and bpfcodes.h in /usr/include/net.
  47.  
  48. (4)    Add an entry for BPF in the character device switch, `cdevsw',
  49.     defined in /sys/{machine}/conf.c (where {machine} can be sun,
  50.     hp300, etc.)  This array contains entry points to the device 
  51.     driver routines    so the kernel can map major device file numbers
  52.     to the appropriate functions.  You need to add bpfopen(), bpfclose(),
  53.     bpfread(), bpfwrite(), bpfioctl(), and bpfselect().
  54.  
  55.     Create the special device files /dev/bpf0, /dev/bpf1, etc.
  56.     Make sure the major device number correpsonds to the entry in
  57.     cdevsw; the minor device number should be the same as the
  58.     trailing digit of the file name.
  59.  
  60.     Access to the packet interface is controlled by the permissions
  61.     on the device files.  We recommend that access be restricted to 
  62.     group `wheel'.  For example, 
  63.  
  64.         /etc/mknod /dev/bpf0 c {major dev} 0
  65.         /etc/mknod /dev/bpf1 c {major dev} 1
  66.         /etc/mknod /dev/bpf2 c {major dev} 2
  67.         ...
  68.         chmod 640 /dev/bpf*
  69.         chgrp wheel /dev/bpf*
  70.  
  71.     The highest allowable minor device number corresponds to the 
  72.     number given in the "pseudo-device" config line (less one).
  73.  
  74. (5)    Modify the link level device drivers to interact with BPF.
  75.     hpdev/if_le.c is an example driver for a LANCE Ethernet
  76.     interface on an hp300 series machine.  [If this is your
  77.     setup, go to (6).]
  78.  
  79.     If you're starting from scratch, this is not too difficult.
  80.     All the BPF mods to hpdev/if_le.c are encapsulated with 
  81.     `#ifdef NBPFILTER > 0', so they're easy to spot.  You need to:
  82.  
  83.     a) Add includes for bpfilter.h and ../net/bpf.h.
  84.  
  85.     b) Add a caddr_t to the softc.  This is the magic cookie
  86.        that tells bpf_tap() who is talking to it.
  87.  
  88.     c) Modify the attach routine to set up some device parameters
  89.        [see hpdev/if_le.c:leattach()] and call bpfattach().
  90.  
  91.     d) Make sure the driver can handle promiscuous operation,
  92.        and that the routine ifpromisc() exists.  Ifpromisc()
  93.        takes an ifp and a flag saying whether to enter or leave
  94.        promiscuous operation.  It should reference count the
  95.        calls and take actions only the last `off' or first `on'.
  96.        The action it should take is setting/clearing the IFF_PROMISC
  97.        bit, and calling the driver's SIOCIFFLAGS ioctl.  The
  98.        driver should inspect the IFF_PROMISC bit and do the right
  99.        thing.
  100.  
  101.     d) Add calls to bpf_tap() at the following places:
  102.  
  103.         i.  Right after the device interrupts and the packet is
  104.             in contiguous interface memory.  This is before
  105.             the packet has been copied in to mbufs.
  106.  
  107.         ii. Right before the packet is transmitted.
  108.             This is after the packet has been copied out of mbufs.
  109.  
  110.         If the packet never exists in contiguous memory
  111.         (some interfaces can follow chains), you need to
  112.         call bpf_mtap instead.
  113.  
  114.         To minimize the cost of the filter when there are no
  115.         listeners, bpf_tap() is only called when the magic
  116.         cookie in the driver's softc is nonzero.  (BPF will
  117.         set and clear it.)
  118.  
  119.         Because BPF can force an interface into promiscuous mode,
  120.         you want to check that incoming packets are destined for
  121.         this host or are broadcast/multicast.  If neither is the 
  122.         case, the packet should be tossed (after calling bpf_tap()).
  123.         This check only needs to be done when there are listeners.
  124.  
  125. (6)    BPF calls the routine ifpromisc() to put an interface into 
  126.     promiscuous mode.  SunOS 4.1 provides this routine; we have
  127.     provided our versions for SunOS 3.5 and BSD in the files
  128.     bpf/net/if-sunos3.c and bpf/net/if-bsd.c.  Merge this code 
  129.     into net/if.c.    Additionally, the `if_pcount' integer field
  130.     must be added to the `struct ifnet' in net/if.h.
  131.  
  132. (7)    That's it.  Run config, make depend, and make, and you're ready to go.
  133.  
  134.  
  135. All the code in these directories is subject to the standard Berkeley 
  136. network software copyright:
  137.  
  138.   Copyright (c) 1990, 1991, 1992 The Regents of the University of California.
  139.   All rights reserved.
  140.  
  141.   Redistribution and use in source and binary forms, with or without
  142.   modification, are permitted provided that: (1) source code distributions
  143.   retain the above copyright notice and this paragraph in its entirety, (2)
  144.   distributions including binary code include the above copyright notice and
  145.   this paragraph in its entirety in the documentation or other materials
  146.   provided with the distribution, and (3) all advertising materials mentioning
  147.   features or use of this software display the following acknowledgement:
  148.   ``This product includes software developed by the University of California,
  149.   Lawrence Berkeley Laboratory and its contributors.'' Neither the name of
  150.   the University nor the names of its contributors may be used to endorse
  151.   or promote products derived from this software without specific prior
  152.   written permission.
  153.   THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
  154.   WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
  155.   MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  156.  
  157.  
  158.  
  159.